home *** CD-ROM | disk | FTP | other *** search
/ Compendium Deluxe 1 / LSD Compendium Deluxe 1.iso / a / disk / misc / scsiutil.lha / SCSIUtil.doc < prev    next >
Encoding:
Text File  |  1994-01-04  |  13.1 KB  |  346 lines
  1. SCSIUtil V2.0 - an utility for doing SCSI low level operations
  2.  
  3.  
  4. SCSIUtil (c) 1991,92,93,94 by Gary Duncan and Heiko Rath
  5.  
  6.  
  7.     Gary Duncan
  8.     Philips PTS
  9.     23 Lakeside Dr
  10.     Tally-Ho Technology Park
  11.     Burwood East Vic 3151
  12.     Australia
  13.  
  14.     EMail: gduncan@philips.oz.au
  15.  
  16.  
  17.     The Software Brewery
  18.     Dipl. Inform. (FH) Heiko Rath
  19.     Raiffeisenstr.10a
  20.     D-64331 Weiterstadt
  21.     Germany
  22.  
  23.     EMail: hr@brewhr.swb.de
  24.  
  25.  
  26.  BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
  27.  FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT
  28.  WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
  29.  PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND,
  30.  EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
  31.  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  32.  PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
  33.  PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME
  34.  THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  35.  
  36.  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
  37.  WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
  38.  REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
  39.  DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
  40.  DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
  41.  (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
  42.  INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE
  43.  OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH
  44.  HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
  45.  DAMAGES.
  46.  
  47.  When redistributing this program ALWAYS redistribute the WHOLE
  48.  archive consisting of:
  49.  
  50.  - DMakefile
  51.  - HISTORY
  52.  - o/SCSIutil.o
  53.  - SCSI_priv.h
  54.  - SCSIutil.c
  55.  - TODO
  56.  - SCSIutil.doc
  57.  - smakefile
  58.  
  59.  The source is provided, therefore you can make changes yourself. The
  60.  only thing I'm asking is that if you do make changes, please get in
  61.  touch with me (hr@brewhr.swb.de), so that we can coordinate any
  62.  further development.
  63.  
  64.  
  65. What is SCSIUtil?
  66. =================
  67.  
  68.  It is a little utility to do some low level stuff with SCSI devices.
  69.  As I currently don't have too much time to work on it (I finished my
  70.  thesis and am now wasting most of my time with a full time job)
  71.  I release it to the public as it is. It is far from being perfect,
  72.  but it is useful to me. In it's current incarnation it has
  73.  the following features:
  74.  
  75.   - read the capacity of a SCSI device
  76.   - read 16 bit raw digital audio off an audio CD (works with Sony CDU
  77.     561 & 8003 & Toshiba 3401) (left/right channel and stereo
  78.     reading supported)
  79.   - read 16 bit raw digital audio off an audio CD and convert to 8 bit
  80.     (left/right channel supported)
  81.   - eject/insert a medium via software control
  82.   - display the Inquiry data of a SCSI device
  83.   - read & interpret a CD-ROM data block address header
  84.   - start/stop the motor on a device
  85.   - read pages via MODE SENSE
  86.   - play audio on a CD-ROM drive (tested with Sony CDU 561 = Apple CD-300
  87.     and Tosiba 3401)
  88.   - read sectors
  89.   - seek to a specified sector
  90.   - display table of contents (TOC) of a CD
  91.   - read subchannel information of a CD (tested with Sony CDU 561)
  92.   - allow/prevent medium removal
  93.  
  94.  
  95. Why SCSIUtil?
  96. =============
  97.  
  98.  I needed some software to explore my new CD-ROM drive.
  99.  
  100.  Here is what SCSIUtil displays, if you invoke it without parameters:
  101.  
  102. SCSIutil V2.0 [Jan  4 1994 : 16:59:03] - written by Gary Duncan
  103.          (gduncan@philips.oz.au) and Heiko Rath (hr@brewhr.swb.de)
  104. Usage: SCSIutil [-dscsi_dev] <scsi_id> <command>
  105.  -c[r]                 : Read capacity [raw]
  106.  -d<l|r|s> sec blks sc : Read 16 bit digital audio(start sector/# blocks)(2)
  107.  -D<l|r> sec blks      : Read  8 bit digital audio(left or right channel)(3)
  108.  -e <0|1>              : Change medium (0=eject, 1=load)
  109.  -i[r]                 : Inquiry [raw]
  110.  -h[r] blk             : Read CD-ROM data block address header
  111.  -l <0|1>              : Allow/Prevent medium removal
  112.  -m <0|1>              : Stop/Start motor {0=stop, 1=start}
  113.  -o[r] contr page      : Mode sense (contr = 0-3))
  114.  -p st si et ei        : Play audio CD track (1-99), index (1-99)
  115.  -r[t] sec_no          : Read sectors [use trackdisk.device]
  116.  -s sec_no             : Seek to sector (5)
  117.  -t[r|l]               : Display TOC of an audio CD [raw|long]
  118.  -u[r] chan fmt track  : Read CD sub-channel information [raw] (6)
  119.  -v [vl0 vl1 vl2 vl3]  : Set output volume channels 0-3 (7)
  120.  
  121. Note 1: usually scsi_id = (BOARD * 100) + (LUN * 10) + SCSI_TARGET_ID
  122.      2: with 's' returns LRLRLR pairs of stereo audio, 2352 bytes per block
  123.         sc = Apple subcode (0=2352, 1=2368, 2=2448, 3=96 byte/block)
  124.      3: converted to 8 bit audio (-d and -D work with Sony CDU 561 & 8003)
  125.      4: contr 0: current, 1: changeable, 2: default, 3: saved values
  126.      5: to park heads, try sec_no of -1
  127.      6: Q-channel = 64, fmt: 0=Sub-Q Channel data,1=current CD-ROM pos.,
  128.         2=Media Catalog Number (UPC/Bar Code),3=Track ISRC
  129.      7: use -1 to leave volume of channel as it is, without argument shows
  130.         current volume settings
  131.  
  132. Documentation on the options of SCSIUtil:
  133. =========================================
  134.  
  135.  -c[r]               : Read capacity [raw]
  136.  
  137.     This will issue a READ CAPACITY to the device to get the
  138.     highest sector available, the sector size and the capacity
  139.     (= sector size * max sector). With the 'r' option SCSIUtil
  140.     will not try to interpret the returned data.
  141.  
  142.     BTW, the Apple CD-300 returns different sector sizes,
  143.     depending on the last read size (that means sometimes it is
  144.     96, 2048 or 2352).
  145.  
  146.  -d<l|r|s> sec blks sc : Read 16 bit digital audio(start sector/# blocks)(2)
  147.  
  148.     This will read data directly from the specified CD-ROM drive,
  149.     interpreting the information as raw digital input. A value for
  150.     the sector to start reading from is required as well as the
  151.     number of sectors to read. The data will be in 16-bit format
  152.     e.g.  SCSIutil 2 -ds 2 100 0 reads the first 100 blocks
  153.     starting from sector 2 as Stereo 16 bit data. One sector
  154.     corresponds to 1/75 of a second.  The data will be output to
  155.     stdout.  This works with the Sony CDU-8003/541/561 (Apple uses
  156.     the CDU-561 in their Apple CD-300).
  157.  
  158.     The sc parameter was tested with the Apple CD-300 and tells
  159.     the drive to return 2352/2368/2448/96 bytes/block. If you're
  160.     only interested in digital audio use sc=0 which just delivers
  161.     588 * 16 bit stereo samples per block = 2352 bytes. If you use
  162.     sc=1 the last 16 bytes contain information about the current
  163.     track/index and timeposition of the sample. Sc = 2 adds 96
  164.     bytes to the raw samples which supposedly contain all the
  165.     subchannels except the Q-subchannel. Usually there won't be
  166.     any useful data in these 96 bytes, but on CD+Graphics and
  167.     CD+Midi CDs (pretty rare) the graphics/midi information is
  168.     encoded. If anybody has some information regarding the
  169.     encoding of CD+G / CD+Midi please get in touch with me!
  170.  
  171.     The digital audio data sent to stdout looks like this (in case
  172.     of sc = 0):
  173.  
  174.     struct cdda_sector {
  175.       struct cdda_sample {
  176.         char left_channel_lsb;
  177.         char left_channel_msb;
  178.         char right_channel_lsb;
  179.         char right_channel_msb;
  180.       } samples[588];
  181.     };
  182.  
  183.     With mono, either the left or right channel is skipped.
  184.  
  185.     BEWARE: sometimes I get SCSI bus lockups while using this
  186.     command. I'm pretty sure that it's not SCSIUtil's fault, but
  187.     either a problem of the WD SCSI chip 33C93A 00-04-PROTO in my
  188.     Amiga 3000 or a firmware bug in the Apple CD-300 (my firmware
  189.     is release 1.8d). The lockups usually occur only if I read
  190.     more than about 150 sectors. When a lockup occurs, don't
  191.     panic! I usually power cycle the Apple CD-300 and everything
  192.     reverts to normal.  BTW, the Apple CD-300 sometimes returns
  193.     the following MODE SENSE errors for no obvious reason:
  194.  
  195.     SENSE_DATA: 70 00 00 00 00 00 00 0a 00 00 00 00 00 00 00 00 00 00
  196.     Error : err=45 , No error
  197.  
  198.     Since V1.905b SCSIUtil reschedules the failed SCSI command and
  199.     tries to reread the missing sectors, thus you shouldn't lose
  200.     any data. (When this happens you might notice a little glitch
  201.     in the digital data, this is caused by the CD-ROM drive's
  202.     inability to access a certain block directly - it might start
  203.     reading +- n sectors before/after the requested block).
  204.  
  205.  -D<l|r> sec blks    : Read  8 bit raw digital audio(left or right channel)(*3*)
  206.  
  207.     Does basically the same as the '-d' option, only divides every
  208.     16 bit word by 256 before sending it to stdout, which makes
  209.     for a cheap (and suboptimal) conversion to 8 bit. The warning
  210.     about SCSI bus lockups applies also to this command. A better way
  211.     to scale to 8 bit would be to find the min/max values in the
  212.     digital data and scale accordingly. Obviously you'd need another
  213.     program to do this job, as otherwise you'd have to keep the
  214.     whole sample in memory to perform this operation.
  215.  
  216.  -e <0|1>            : Change medium (0=eject, 1=load)
  217.  
  218.     By using this command you can eject a removable medium via
  219.     software, e.g. SCSIutil 2 -e 0 ejects the CD-ROM currently in
  220.     the drive with SCSI id 2.
  221.  
  222.  -i[r]               : Inquiry [raw]
  223.  
  224.     This command sends the INQUIRY command to the specified
  225.     device. This can be used to get all kinds of information about
  226.     the device. With the 'r' parameter SCSIUtil will not try to
  227.     interpret the information returned.
  228.  
  229.  -h[r] blk           : Read CD-ROM data block address header
  230.  
  231.     This will read the address header information of a particular
  232.     CD-ROM block, e.g. SCSIutil 2 -h 100 reads block 100 from SCSI
  233.     device 2 and returns the header information.
  234.  
  235.  -l <0|1>            : Allow/Prevent medium removal
  236.  
  237.     This command sends a PREVENT ALLOW MEDIUM REMOVAL to the SCSI
  238.     device.
  239.  
  240.  -m <0|1>            : Stop/Start motor {0=stop, 1=start}
  241.  
  242.     Start or stop the device motor of the specified device.
  243.     SCSIutil 2 -m 0 stops a CD that is playing in SCSI device 2.
  244.  
  245.  -o[r] contr page    : Mode sense (contr = 0-3)) (*4*)
  246.  
  247.     Reads MODE SENSE control pages from a SCSI device. The contr
  248.     parameter decides what pages to return:
  249.  
  250.     contr 0: current values
  251.               1: changeable values (not interpreted correctly by SCSIUtil)
  252.               2: default values
  253.               3: saved values
  254.  
  255.     The page value must be in the range of 0-63. Page 63 usually
  256.     returns all the available MODE SENSE pages.  With the 'r'
  257.     option SCSIUtil will not interpret the returned data.
  258.  
  259.  -p st si et ei      : Play audio CD track (1-99), index (1-99)
  260.  
  261.     Allows the playing of a series of audio tracks. Can use index
  262.     marks as well e.g. SCSIutil 2 -p 1 1 8 1 plays an Audio CD in
  263.     SCSI device 5 from Track 1 to Track 8.
  264.     Track and Index should be in the range of 1-99 (according to
  265.     the ANSI SCSI 2 specs). The Apple CD-300 accepts an index of 0
  266.     as play whole track, therefore I allowed the selection of 0 as
  267.     an index, even though the online help states otherwise. To
  268.     play a whole CD type: scsiutil 2 -p 1 0 99 0. To play only
  269.     track 3: scsiutil 2 -p 3 1 3 1.
  270.  
  271.  -r[t] sec_no        : Read sectors [use trackdisk.device]
  272.  
  273.     Read data sector off a SCSI device. In case of an audio CD use
  274.     the -d or -D commands to read digital audio data.
  275.  
  276.  -s sec_no           : Seek to sector (*5*)
  277.  
  278.     Seek the head of a device to the specified sector.
  279.  
  280.  -t[r|l]             : Display TOC of an audio CD [raw|long]
  281.  
  282.     Reads the table of contents of a CD. The TOC can contain
  283.     entries for data/audio tracks.  With the 'r' option SCSIUtil
  284.     won't interpret the returned data. With the 'l' option
  285.     SCSIUtil will display the TOC in a longer form.
  286.  
  287.  -u[r] chan fmt track: Read CD sub-channel information [raw] (*6*)
  288.  
  289.     Reads information from the specified sub-channel of a CD.
  290.  
  291.     Chan = 64 = Q-Sub-channel
  292.     Fmt 0: read Q-sub-channel
  293.      Doesn't work with the Apple CD-300 drive
  294.     Fmt 1: read current position data
  295.      Track must be 0
  296.     Fmt 2: read media catalog number (UPC/Bar Code)
  297.      Track must be 0
  298.     Fmt 3: read track international standard recording code (ISRC)
  299.      Track must be a valid track
  300.  
  301.     With the 'r' option SCSIUtil doesn't try to interpret the
  302.     returned data.
  303.  
  304.  -v [vl0 vl1 vl2 vl3]  : Set output volume channels 0-3 (7)
  305.  
  306.     Allows you to set the volume of the CD-ROM audio channels.
  307.     Values in the range of 0-255 are allowed. If you use -1 this
  308.     channel won't be affected. If -v is issued without additional
  309.     parameter, SCSIUtil will display the current volume settings.
  310.  
  311. The future:
  312. ===========
  313.  
  314.  There are several things that I'd like to implement, take a look at
  315.  the TODO file. If you have a need for some additional features you
  316.  can always try to talk me into implementing them (hint: I can be
  317.  bribed ;-)
  318.  
  319.  
  320. Acknowledgements:
  321. =================
  322.  
  323.  Fred Fish for his work for the Amiga community
  324.  
  325.  Gary Duncan (gduncan@philips.oz.au) for having written the original
  326.     version and releasing the source to the public
  327.  
  328.  Dave Hassal (dave@ainfo.equinox.gen.nz) for bugging me with questions
  329.     and pushing me into finishing SCSIUtil.
  330.  
  331.  Stefan Becker (stefanb@yello.adsp.sub.org) for supplying patches to allow
  332.     reading of digital audio with the Toshiba XM3401 and DICE-support.
  333.  
  334.  Ralph Babel for some _very useful_ hints/tips/tricks.
  335.  
  336.  Franz-Josef Reichert for his Jukebox.
  337.  
  338.  Frank Munkert (ln_fmu@pki-nbg.philips.de) for AmiCDROM, PlayCDDA
  339.     and some good suggestions.
  340.  
  341.  Free Software Foundation, Inc. for the no warranty text and use at
  342.     your own risk texts. Also thanks for some high quality SW.
  343.  
  344.  My fellow Software Brewers (Christian Balzer & Armin Sparr) for
  345.     support.
  346.